為什麼從 OTP 微服務開始？

昨天我們設計了完整的 Kyo-System 架構，今天要開始規劃第一個微服務：OTP 驗證服務。主要是這個是新的客戶需求，自從開始打造SaaS產品之後，新的需求都會打造成微服務。

OTP 服務是很好的開始，因為：

• 需求明確：發送驗證碼、驗證驗證碼
• 技術範圍可控：不會太複雜，適合建立基礎架構
• 可重複使用：未來所有專案都可以使用
• 商業價值：可以作為獨立業務服務銷售

核心功能規劃

• OTP 發送：整合三竹簡訊 API，支援自訂模板
• OTP 驗證：六位數驗證碼，防暴力破解機制
• 管理介面：React 前端，模板管理與發送記錄
• API 介面：REST (外部整合) + ORPC (內部管理)

MVP 成功指標

• 99.9% 成功率，P95 延遲 < 300ms
• 支援每小時 1,000+ OTP 發送
• 完整的監控與告警機制

建立 Monorepo 基礎結構

1. 初始化專案

# 建立專案目錄
mkdir kyong-saas && cd kyong-saas

# 初始化 package.json
pnpm init

# 設定為私有專案和 workspace
echo '{"name": "kyo-system", "private": true, "packageManager": "pnpm@9"}' > package.json

2. 建立 Workspace 配置

# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'

3. 安裝 Turborepo

# 安裝 Turborepo 作為建置工具
pnpm add -D turbo@^2.0.0 typescript@^5.5.0

# 建立 Turborepo 配置
echo '{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": { "dependsOn": ["^build"], "outputs": ["dist/**"] },
    "dev": { "cache": false },
    "lint": {},
    "test": {}
  }
}' > turbo.json

建立專案目錄結構

4. 建立標準目錄

# 應用程式目錄
mkdir -p apps/kyo-dashboard apps/kyo-otp-service

# 共享套件目錄
mkdir -p packages/kyo-core packages/kyo-types packages/kyo-ui packages/kyo-config

# 基礎設施目錄
mkdir -p infra/aws-cdk

# 開發工具目錄
mkdir -p tools/scripts

5. 建立根目錄腳本

// package.json (更新 scripts 部分)
{
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev",
    "lint": "turbo run lint",
    "test": "turbo run test",
    "clean": "turbo run clean"
  }
}

設定共享套件基礎

6. 建立 @kyong/kyo-types 套件

cd packages/kyo-types

# 初始化套件
pnpm init

// packages/kyo-types/package.json
{
  "name": "@kyong/kyo-types",
  "version": "0.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "dev": "tsc -w -p tsconfig.json"
  },
  "devDependencies": {
    "typescript": "^5.5.0",
    "zod": "^3.23.8"
  }
}

7. 建立基礎型別定義

mkdir packages/kyo-types/src

# 建立基礎型別檔案
touch packages/kyo-types/src/index.ts
touch packages/kyo-types/src/errors.ts
touch packages/kyo-types/src/schemas.ts

設定 TypeScript 配置

8. 建立根目錄 TypeScript 配置

// tsconfig.base.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "declaration": true,
    "outDir": "dist"
  },
  "exclude": ["node_modules", "dist"]
}

9. 各套件繼承基礎配置

// packages/kyo-types/tsconfig.json
{
  "extends": "../../tsconfig.base.json",
  "include": ["src/**/*"],
  "compilerOptions": {
    "rootDir": "src"
  }
}

建立開發工具配置

10. 設定 ESLint 和 Prettier

# 安裝代碼品質工具
pnpm add -D @typescript-eslint/eslint-plugin @typescript-eslint/parser eslint prettier

# 建立 ESLint 配置
echo '{
  "extends": ["@typescript-eslint/recommended"],
  "parser": "@typescript-eslint/parser",
  "plugins": ["@typescript-eslint"],
  "ignorePatterns": ["dist/", "node_modules/"]
}' > .eslintrc.json

# 建立 Prettier 配置
echo '{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5"
}' > .prettierrc

11. 建立 Git 忽略檔案

# .gitignore
echo 'node_modules/
dist/
.env
.env.local
.DS_Store
*.log' > .gitignore

設定環境變數管理

12. 建立環境變數範本

# .env.example
echo '# Database
DATABASE_URL="postgresql://user:password@localhost:5432/kyo"

# Redis
REDIS_URL="redis://localhost:6379"

# Mitake SMS (將從 AWS Secrets Manager 讀取)
MITAKE_USERNAME=""
MITAKE_PASSWORD=""
MITAKE_ENDPOINT=""

# Development
NODE_ENV="development"' > .env.example

驗證專案結構

13. 檢查目錄結構

tree -I 'node_modules' -L 3

預期輸出：

kyong-saas/
├── apps/
│   ├── kyo-dashboard/
│   └── kyo-otp-service/
├── packages/
│   ├── kyo-core/
│   ├── kyo-types/
│   ├── kyo-ui/
│   └── kyo-config/
├── infra/
│   └── aws-cdk/
├── package.json
├── pnpm-workspace.yaml
├── turbo.json
└── tsconfig.base.json

初始化測試

14. 測試 Turborepo 運作

# 安裝所有相依性
pnpm install

# 測試建置指令
pnpm run build

# 測試 workspace 是否正常
pnpm -r list